PhAST - Apps¶

Apps¶

Apps são pequenas aplicações em scripts que dependem de uma aplicação maior, nossa plataforma PhAST, que o executa de uma forma controlada, através de regras estabelecidas.

Observando o macro-diagrama presente na documentação de arquitetura da Plataforma Phoebus para terminais POS, podemos observar algumas características interessantes sobre os Apps:

Linguagem: Os Apps são escritos em Java Script Lite baseada na linguagem WMLS, e com uso de uma API de extensão.

Execução: Os Apps são executados pela máquina virtual Phoebus (PhVM).

Concorrência: O PhAST gerencia um ou mais Apps existente no terminal.

Definições do App¶

Apps se registram junto ao PhAST através de um arquivo com extensão INI que possui parâmetros relacionado aos Apps. Segue exemplo de um arquivo INI:

applet.ini

[Applet]
TESTE=package: //teste/teste.wmlsc

[TESTE]
teste.limite.transacoes=100

Onde:

[APPLET] - Define PhScript principal do App. Este PhScript serve de Entry Point para o App.
[TESTE] - Define a entrada de parâmetros para o App que se está definido. Vários parâmetros podem ser adicionados neste ponto. Todos definidos pelo App.

Configurações Locais¶

O PhAST reserva uma área em suas próprias configurações locais para que cada App possa também persistir suas respectivas configurações locais.

As configurações locais são estruturas PhType.STRUCT associadas a cada App. Onde cada um destes Apps, pode livremente persistir dados em suas respectivas estruturas.

Configurações de Inicialização¶

O PhAST também possibilita que cada App adicione informações customizadas na requisição de inicialização do terminal junto ao Host do PhAST.

Não é muito comum Apps realizarem tais informações. Atualmente apenas os Apps residentes Phoebus utilizam tais recursos.

Serviços¶

Existe um conceito criado no PhAST para uso nos Apps que é o de serviços públicos. Com esse conceito, cada App por publicar para o PhAST sua lista de serviços que o mesmo deseja oferecer aos demais Apps.

Por exemplo, um App de pagamento pode publicar serviços relacionados a pagamentos para que outros Apps utilizem, sem que estes necessite conhecer o App que os publicou.

Para meiores detalhes, favor consultar a documentação da API de serviços do PhAST.

Funções de integração¶

O PhAST define pontos de integração com o App. Esses pontos servem para que o App seja iniciado junto com o PhAST, notificado de ocorrências no terminal e etc. São eles:

init
main
term
resetInitCfg
resetSpecCfg
setup
outset
showidleScreen
onCheckInstallation
publicServices
OnAcceptTCPConnection
addAppletToIdleScreen
start
refreshIdleScreen
onIdle
onIdleRefresh
onCheckInstallation
unlock
onError
getDataFileNames
getConfigFileNames
onEventStart
onEventFinish
onLogin
onLogout
onShiftOpen
onShiftClose
onChipCardDetected
onMagCardDetected
onManualCardDetected
notifyAppletInstallation
onAddFieldsUpdate
onUninstall
onAfterCloseLote

Todas as funções de integração aqui apresentadas, quando utilizadas precisam ser declaradas como extern.

init(Applet)¶

Esta função é chamada pela gerência de Apps do PhAST no processo de boot do terminal POS. É importante destacar que o PhAST primeiro realiza seu próprio processo de init para depois chamar os inits dos Apps registrado no POS, obedecendo a ordem de definição dos Apps.

Parâmetros¶
+ **Applet** - É um mapa relacionado aos parâmetros presentes no arquivo .INI do respectivo Applet.
Retorno¶
Retorna um booleano indicando:
+ **true** - Quando todo o processo de boot do App funcionou
false - Quando houve alguma falha

É importante mencionar que quando um App falha em seu processo de boot, o mesmo será desativado pelo PhAST, não permitindo assim que o mesmo seja executado.

main()¶

Esta função é definida caso um App queira assumir totalmente o fluxo de execução do PhAST. Algo de extrema importância é que apenas um App deve possuir o main, caso contrário o phast executará sequenciadamente a função main de todos os Apps ativos.

Normalmente os Apps não necessitam assumir essa responsabilidade, logo não necessitam conter a função main em seu PhScript. Com isso o App é executado através do fluxo natural do PhAST.

Parâmetros¶
+ **Nenhum**
Retorno¶
Retorna um booleano indicando:
+ **true** - Possui e executou o fluxo principal
false - Possui, mas não executou o fluxo principal

O melhor tratamento para essa questão do App querer assumir ou não o fluxo principal é:

Quer assumir: Define a função main em seu PhScript e nele retorna true.

Não quer assumir: Não define a função main em seu PhScript.

term()¶

Esta função é chamada quando o App está sendo encerrado junto com o PhAST.

Parâmetros¶
+ **Nenhum**
Retorno¶
+ **Nenhum**

Antes do encerramento do PhAST, este chama o encerramento de todos os Apps ativos do terminal.

resetInitCfg(dataList)¶

Esta função é chamada quando o terminal é configurado pela primeira vez ou quando o terminal teve toda a sua configuração removida. Trata-se de configurações necessárias para enviar ao HOST na instalação do terminal.

Parâmetros¶
+ **dataList** - PhType.STRUCT que será o conteúdo das configurações do App na instalação do terminal.
Retorno¶
Retorna um booleano indicando:
+ **true** - Configuração bem sucedida
false - Falha na configuração

Normalmente os Apps não-residentes não necessitam enviar configurações específicas ao HOST PhAST.

resetSpecCfg(dataList)¶

Esta função é chamada quando o terminal é configurado pela primeira vez ou quando o terminal teve toda a sua configuração removida. Trata-se de configurações locais ao terminal que o App deseja armazenar.

Parâmetros¶
+ **dataList** - PhType.STRUCT que será o conteúdo das configurações locais do App.
Retorno¶
Retorna um booleano indicando:
+ **true** - Configuração bem sucedida
false - Falha na configuração

setup()¶

Função chamada após configuração bem sucedida do terminal POS em seu processo de instalação. Através dessa função de integração, o App tem a oportunidade de também capturar informações importante para ele.

Parâmetros¶
+ **Nenhum**
Retorno¶
+ **Nenhum**

outset()¶

Função chamada pelo PhAST após ele concluir todo o processo de boot. É uma notificação mais tardia, em relação à função init, de início da aplicação.

Parâmetros¶
+ **Nenhum**
Retorno¶
Retorna um booleano indicando:
+ **true** - Em caso de sucesso na notificação
false - Em caso de falha

showidleScreen(list)¶

Função chamada pelo PhAST sempre que a tela de IDLE do POS for exibida. Isso garante que sempre que o POS for realizar uma transação, ou executar um evento, assim que o mesmo voltar para tela de IDLE, todos os Apps ativos serão notificados.

Parâmetros¶
+ **list** - PhList contendo dois elementos:
+ mensagem - Mensagem exibida na tela de IDLE, normalmente a mensagem de "Insira ou passe o cartão"
+ contador (DEPRECATED)
Retorno¶
**Nenhum**

onCheckInstallation(inicUpdated)¶

Função chamada pelo PhAST sempre que ocorre uma inicialização. Um detalhe importante é que se ocorrer algum erro, a função não é chamada. Dessa forma, podemos garantir que a função apenas é chamada ao final de uma inicialização concluída com sucesso.

Parâmetros¶
+ **inicUpdated** - Indica se a inicialização alterou alguma configuração do POS.
Retorno¶
Retorna um booleano indicando:
+ **true** - Em caso de sucesso na notificação
false - Em caso de falha

Uma observação importante é que se algum App retornar false nesta função, o terminal entenderá que toda a inicialização necessita ser realizada novamente.

publicServices()¶

Função chamada pelo PhAST afim de verificar se o App deseja publicar serviços, contendo funcionalidades úteis para qualquer App, mas preservando quem está executando.

Parâmetros¶
+ **Nenhum**
Retorno¶
**Nenhum**
Observações:¶
+ **Registro**: O registro dos serviços é feito através da função *register* do módulo *package://phast#Applet/service.wmlsc*
Execução: A execução de serviços é feita através da função execute do módulo package://phast#Applet/service.wmlsc

Para maiores detalhes, consultar a API do PhAST.

OnAcceptTCPConnection(socket)¶

Função chamada pelo phast para notificar a chegada de uma conexão socket através da porta que o mesmo App solicitou para listen.

Parâmetros¶
+ **socket** - Socket que pode ser manipulado com Stream
Retorno¶
**Nenhum**
Observação¶
+ **Servidor**: Um App pode solicitar que uma porta esteja em listen através do parâmetro "port" definido em seu conjunto de definições.
+ **Desconexão**: Após o retorno da função *OnAcceptTCPConnection* para o PhAST, este realizará a desconexão do socket estabelecido.

addAppletToIdleScreen()¶

Possibilita que o App adicione um botão funcional no menu de Apps da tela de IDLE do PhAST.

Parâmetros¶

Nenhum

Retorno¶

return - invalid ou PHList - com sub listas contendo o formato de [LABEL, SHORTCUTKEY, SCRIPT]. Retorna uma lista (PhList) com a definição do botão, como detalhado a seguir:

Label - Label do botão;

Atalho - Atalho de teclado para o botão;

Função - Caminho completo da função PhScript a ser executada quando o botão for acionada. Esta função não pode ter parâmetros;

Observações¶

A função que recebe o evento de acionamento do botão, além de precisar ser definida como externa, não pode ter parâmetros.

O valor inteiro referente ao ATALHO inserido na lista não pode ser repetido entre os demais apps em execução, havendo conflito, este inteiro deve ser alterado para um outro valor disponível.

A tela principal suporta até seis (6) botões.

Exemplo¶
extern function addAppletToIdleScreen()
{
  var result  = [];
  var bt = ["Teste", 14, "package://hello/hello.wmlsc#start"];
  PhList.add(result, bt);
  return result;
}

start()¶

Função de entrada caso App seja usado junto com módulo PayStore. Se instalado, é executada ao clicar no App na store.

Parâmetros¶
**Nenhum**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

refreshIdleScreen()¶

Função chamada no primeiro draw da tela de Idle, junto dos demais Apps na VM, seguindo ordem de inicialização.

Parâmetros¶
+ **progress:Integer** - progresso interno com uso junto ao PHDM
+ **title:String**     - @ref showIdleScreen
+ **msg1:String**      - @ref showIdleScreen
+ **msg2:String**      - @ref showIdleScreen
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onIdle()¶

Função chamada ao final do primeiro draw da tela de Idle, junto dos demais Apps na VM, seguindo ordem de inicialização

Parâmetros¶
**Nenhum**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onIdleRefresh()¶

Função chamada ao final de cada refresh da tela de Idle, junto dos demais Apps na VM, seguindo ordem de inicialização

Parâmetros¶
**Nenhum**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onCheckInstallation()¶

Função chamada ao final da inicialização da aplicação com servidor, junto dos demais Apps na VM, seguindo ordem de inicialização

Parâmetros¶
+ **inicUpdated:Boolean ** - indicando sucesso na extração dos arquivos da resposta da inicialização
Retorno¶
**true ou false**
Observação¶
**Nenhum**

unlock()¶

Função chamada quando estado da aplicação se encontra em #ST_LOCKED, junto dos demais Apps na VM, seguindo ordem de inicialização.

Parâmetros¶
**Nenhum**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onError()¶

Função que recebe código de erro vindo da VM depois da exibição da tela de erro

Parâmetros¶
+ **code:Integer ** - código do erro passado.
Retorno¶
**true ou false**
Observação¶
**Nenhum**

getDataFileNames()¶

...

Parâmetros¶
+ **list**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

getConfigFileNames()¶

...

Parâmetros¶
+ **list**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onEventStart()¶

...

Parâmetros¶
**type**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onEventFinish()¶

...

Parâmetros¶
+ **type**
+ **result**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

...

Parâmetros¶
+ **login**
+ **online**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onLogout()¶

...

Parâmetros¶
**Nenhum**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onShiftOpen()¶

...

Parâmetros¶
+ **userId**
+ **shiftId**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onShiftClose()¶

...

Parâmetros¶
+ **userId**
+ **shiftId**
+ **date**
Retorno¶
**Nenhum**
Observação¶
**Nenhum**

onChipCardDetected(transactionId, appType)¶

Função que será executada ao ser inserido um cartão com chip no terminal.

Parâmetros¶
+ **transactionId** - Identificador da operação.
+ **appType**       - Tipo de Operação selecionada (Débito ou Crédito)
Retorno¶
+ **true** - Informa ao Phast que a responsabilidade é do app que retornou o tratamento desse evento, dessa forma o Phast não irá exibir o menu de pagamento padrão.
false - Indica que a responsabilidade de tratar o evento é do Phast, que seguirá o comportamento padrão.

Observação¶
**Nenhum**

onMagCardDetected(transactionId)¶

Função que será executada ao passar um cartão com tarja magnética.

Parâmetros¶
+ **transactionId** - Identificador da operação.
Retorno¶
+ **true** - Informa ao Phast que a responsabilidade é do app que retornou o tratamento desse evento, dessa forma o Phast não irá exibir o menu de pagamento padrão.
false - Indica que a responsabilidade de tratar o evento é do Phast, que seguirá o comportamento padrão.

Observação¶
**Nenhum**

onManualCardDetected(transactionId)¶

Função que será executada ao inserir o número do cartão de forma manual.

Parâmetros¶
+ **transactionId** - Identificador da operação.
Retorno¶
**true ou false**
Observação¶
**Nenhum**

notifyAppletInstallation(app)¶

Notifica a todos os Apps instalados quando a instalação de um novo App for concluida.

Parâmetros¶

+ **app** - PhList contendo dados da aplicação:

          [0] - String packageName, nome do pacote do app.
          [1] - String appName, nome do app.
          [2] - String appVersion, versão do app.
          [3] - String mainScript, caminho do script principal do app.
          [4] - String appType, tipo do app (App ou skin).

Retorno¶

**nenhum**

Observação¶

**Nenhum**

onAddFieldsUpdate()¶

Notifica a todos os Apps instalados quando os campos adicionais sofrerem atualização.

Parâmetros¶
**nenhum**
Retorno¶
**nenhum**
Observação¶
**Nenhum**

onUninstall()¶

Notifica a todos os Apps instalados que houve desistalação de um App.

Parâmetros¶
**nenhum**
Retorno¶
**nenhum**
Observação¶
**Nenhum**

onAfterCloseLote()¶

Função será executada após fechamento de lote.

Parâmetros¶
**nenhum**
Retorno¶
**nenhum**
Observação¶
**Nenhum**